//////////////////////////////////////////////////////////////////////
//
// File: IHmeProtocol.java
//
// Copyright (c) 2003-2005 TiVo Inc.
//
//////////////////////////////////////////////////////////////////////

package com.tivo.hme.sdk;

/**
 * HME Protocol constants.
 *
 * <p>CMD_* constants are the command codes for the HME protocol.
 *
 * <p>EVT_* constants are the event types in the HME protocol.
 *
 * <p>RSRC_* constants are resource flags, they define how to fit a resource
 * into a view.
 *
 * <p>RSRC_STATUS_* constants are the codes for the various states of a
 * resource.
 *
 * <p>TRANSITION_* constants are the codes for the various transition
 * types that can be sent in a CMD_RECEIVER_TRANSITION message.
 *
 * <p>APP_ERROR_* and RSRC_ERROR_* constants are enumerate application and
 * resource error states respectively.
 * 
 * <p>ID_* constants reserve some predefined IDs in the system,
 * e.g. for system resources.
 * 
 * <p>KEY_* constants represent key codes that can be generated by the user on
 * any receiver.  It is safe for applications to make functionality only
 * accessible via these keys.
 *
 * <p>KEY_OPT_* constants represent key codes that may be present on
 * any receiver, but are not guaranteed to be present.  It is not wise
 * for applications to make functionality only accesible via one of
 * these keys since they may not be available to the user on some
 * receiver implementations.
 *
 * <p>Some keys are reserved for internal use, developers should not expect
 * these keys to be passed to their applications.
 *
 * <p>Protocol limits are defined by the LIMIT_* constants.
 *
 * <p>The title and action safe regions of the screen are defined by the SAFE_*
 * constants.
 * 
 * @author      Adam Doppelt
 * @author      Arthur van Hoff
 * @author      Brigham Stevens
 * @author      Jonathan Payne
 * @author      Steven Samorodin
 */
public interface IHmeProtocol
{
    /** Protocol magic number 'SBTV'. */
    int MAGIC                           = 0x53425456;

    /** Current major version number. */
    int VERSION_MAJOR                   = 0;

    /** Current minor version number. */
    int VERSION_MINOR                   = 41;

    /** The entire current version number (major << 8) | minor. */
    int VERSION                         = (VERSION_MAJOR << 8) | VERSION_MINOR;

    /** Version number for version 0.38. */
    int VERSION_0_38                    = (0 << 8) | 38;

    /**
     * Version number for version 0.40.  This is the version when vUInts were
     * introduced for string lengths.
     */
    int VERSION_0_40                    = (0 << 8) | 40;

    /** The version number as a string. */
    String VERSION_STRING               = VERSION_MAJOR + "." + VERSION_MINOR;

    //
    // commands
    //

    /** Command view add. */
    int CMD_VIEW_ADD                    = 1;

    /** Command view set bounds. */
    int CMD_VIEW_SET_BOUNDS             = 2;

    /** Command view set scale. */
    int CMD_VIEW_SET_SCALE              = 3;

    /** Command view set translation. */
    int CMD_VIEW_SET_TRANSLATION        = 4;

    /** Command view set transparency. */
    int CMD_VIEW_SET_TRANSPARENCY       = 5;

    /** Command view set visible. */
    int CMD_VIEW_SET_VISIBLE            = 6;

    /** Command view set painting. */
    int CMD_VIEW_SET_PAINTING           = 7;

    /** Command view set resource. */
    int CMD_VIEW_SET_RESOURCE           = 8;

    /** Command view remove. */
    int CMD_VIEW_REMOVE                 = 9;


    /** Command resource add color. */
    int CMD_RSRC_ADD_COLOR              = 20;

    /** Command resource add truetype font. */
    int CMD_RSRC_ADD_TTF                = 21;

    /** Command resource add font. */
    int CMD_RSRC_ADD_FONT               = 22;

    /** Command resource add text. */
    int CMD_RSRC_ADD_TEXT               = 23;

    /** Command resource add image. */
    int CMD_RSRC_ADD_IMAGE              = 24;

    /** Command resource add sound. */
    int CMD_RSRC_ADD_SOUND              = 25;

    /** Command resource add stream. */
    int CMD_RSRC_ADD_STREAM             = 26;

    /** Command resoruce add animation. */
    int CMD_RSRC_ADD_ANIM               = 27;


    /** Command resource set active. */
    int CMD_RSRC_SET_ACTIVE             = 40;

    /** Command resource set position. */
    int CMD_RSRC_SET_POSITION           = 41;    

    /** Command resource set speed. */
    int CMD_RSRC_SET_SPEED              = 42;

    /** Command resource send event. */
    int CMD_RSRC_SEND_EVENT             = 44;

    /** Command resource close. */
    int CMD_RSRC_CLOSE                  = 45;

    /** Command resource remove. */
    int CMD_RSRC_REMOVE                 = 46;


    /** Command acknowledge idle. */
    int CMD_RECEIVER_ACKNOWLEDGE_IDLE   = 60;

    /** Command transition. */
    int CMD_RECEIVER_TRANSITION         = 61;
    

    /** Reserved. */
    int CMD_RESERVED                    = 2047;

    //
    // events
    //

    /** Device info event. */
    int EVT_DEVICE_INFO                 = 1;

    /** Application info event. */
    int EVT_APP_INFO                    = 2;

    /** Resource info event. */
    int EVT_RSRC_INFO                   = 3;

    /** Key event. */
    int EVT_KEY                         = 4;

    /** Idle event. */
    int EVT_IDLE                        = 5;

    /** Font info event. */
    int EVT_FONT_INFO                   = 6;

    /** Init info event. */
    int EVT_INIT_INFO                   = 7;

    /** Reserved. */
    int EVT_RESERVED                    = 2047;

    //
    // font styles
    //

    /** Font style, plain. */
    int FONT_PLAIN                      = 0x00;

    /** Font style, bold. */
    int FONT_BOLD                       = 0x01;

    /** Font style, italic. */
    int FONT_ITALIC                     = 0x02;

    /** Font style, bold and italic. */
    int FONT_BOLDITALIC                 = 0x03;

    //
    // font metrics flags
    //
    
    /** Just the basic font metrics that apply to all glyphs. */
    int FONT_METRICS_BASIC              = 0x01;

    /** Specific metrics for each glyph in the standard ASCII char set. */
    int FONT_METRICS_GLYPH              = 0x02;
    
    //
    // rsrc flags
    //

    /** Resource flag, left horizontal alignment. */
    int RSRC_HALIGN_LEFT		= 0x0001;

    /** Resource flag, center horizontal alignment. */
    int RSRC_HALIGN_CENTER		= 0x0002;

    /** Resource flag, right horizontal alignment. */
    int RSRC_HALIGN_RIGHT		= 0x0004;

    /** Resource flag, horizontal alignment mask. */
    int RSRC_HALIGN_MASK		= 0x0007;

    /** Resource flag, top vertical alignment. */
    int RSRC_VALIGN_TOP			= 0x0010;

    /** Resource flag, center vertical alignment. */
    int RSRC_VALIGN_CENTER		= 0x0020;

    /** Resource flag, bottom vertical alignment. */
    int RSRC_VALIGN_BOTTOM		= 0x0040;

    /** Resource flag, vertical alignment mask. */
    int RSRC_VALIGN_MASK		= 0x0070;

    /** Resource flag, text wrap. */
    int RSRC_TEXT_WRAP			= 0x0100;

    /** Resource flag, text mask. */
    int RSRC_TEXT_MASK                  = 0x0700;

    /** Resource flag, image horizontal fit. */
    int RSRC_IMAGE_HFIT			= 0x1000;

    /** Resource flag, image vertical fit. */
    int RSRC_IMAGE_VFIT			= 0x2000;

    /** Resource flag, image best fit. */
    int RSRC_IMAGE_BESTFIT		= 0x4000;

    /** Resource flag, image mask. */
    int RSRC_IMAGE_MASK			= 0x7000;

    // 
    // transition types
    // 

    /** Transition forward to another place. */
    int TRANSITION_FORWARD              = 1;

    /** Transition backwards to the previous place. */
    int TRANSITION_BACK                 = 2;

    /** Transition directly (teleport) to another place. */
    int TRANSITION_TELEPORT             = 3;

    //
    // predefined ids
    //
    /** ID of the empty resource */
    int ID_NULL                         = 0;

    /** ID of the root application stream. */
    int ID_ROOT_STREAM                  = 1;

    /** ID of the root application's root view. */
    int ID_ROOT_VIEW                    = 2;

    /** ID of the default built-in TrueType font system resource. */
    int ID_DEFAULT_TTF                  = 10;

    /** ID of the system built-in TrueType font system resource. */
    int ID_SYSTEM_TTF                   = 11;

    /** ID of the system built-in bonk system sound resource. */
    int ID_BONK_SOUND                   = 20;

    /** ID of the system built-in up/down arrow system sound resource. */
    int ID_UPDOWN_SOUND                 = 21;

    /** ID of the system built-in thumbs up system sound resource. */
    int ID_THUMBSUP_SOUND               = 22;

    /** ID of the system built-in thumbs down system sound resource. */
    int ID_THUMBSDOWN_SOUND             = 23;

    /** ID of the system built-in select system sound resource. */
    int ID_SELECT_SOUND                 = 24;

    /** ID of the system built-in TiVo&reg; system sound resource. */
    int ID_TIVO_SOUND                   = 25;

    /** ID of the system built-in left arrow system sound resource. */
    int ID_LEFT_SOUND                   = 26;

    /** ID of the system built-in right arrow system sound resource. */
    int ID_RIGHT_SOUND                  = 27;

    /** ID of the system built-in page up system sound resource. */
    int ID_PAGEUP_SOUND                 = 28;

    /** ID of the system built-in page down system sound resource. */
    int ID_PAGEDOWN_SOUND               = 29;

    /** ID of the system built-in alert system sound resource. */
    int ID_ALERT_SOUND                  = 30;

    /** ID of the system built-in deselect system sound resource. */
    int ID_DESELECT_SOUND               = 31;

    /** ID of the system built-in error system sound resource. */
    int ID_ERROR_SOUND                  = 32;

    /** ID of the system built-in trickplay slowdown system sound resource. */
    int ID_SLOWDOWN1_SOUND              = 33;

    /** ID of the system built-in trickplay speedup 1 system sound resource. */
    int ID_SPEEDUP1_SOUND               = 34;

    /** ID of the system built-in trickplay speedup 2 system sound resource. */
    int ID_SPEEDUP2_SOUND               = 35;

    /** ID of the system built-in trickplay speedup 3 system sound resource. */
    int ID_SPEEDUP3_SOUND               = 36;

    int ID_RESERVED                     = 2047;
    
    /**
     * Resource ID of first client resource, for receivers supporting versions
     * before 0.38.
     */
    int ID_CLIENT_PRE_0_38              = 100;

    /** Resource ID of first client resource. */
    int ID_CLIENT                       = 2048;

    //
    // media status codes
    //

    /** Media status code, resource status unknown. */
    int RSRC_STATUS_UNKNOWN             = 0;

    /** Media status code, resource connecting. */
    int RSRC_STATUS_CONNECTING          = 1;

    /** Media status code, resource connected. */
    int RSRC_STATUS_CONNECTED           = 2;

    /** Media status code, resource loading. */
    int RSRC_STATUS_LOADING             = 3;

    /** Media status code, resource ready. */
    int RSRC_STATUS_READY               = 4;

    /** Media status code, resource playing. */
    int RSRC_STATUS_PLAYING             = 5;

    /** Media status code, resource paused. */
    int RSRC_STATUS_PAUSED              = 6;

    /** Media status code, resource seeking. */
    int RSRC_STATUS_SEEKING             = 7;

    /** Media status code, resource closed. */
    int RSRC_STATUS_CLOSED              = 8;

    /** Media status code, resource complete. */
    int RSRC_STATUS_COMPLETE            = 9;

    /** Media status code, resource error. */
    int RSRC_STATUS_ERROR               = 10;

    //
    // application errors
    //

    /** Application error, error unknown. */
    int APP_ERROR_UNKNOWN               = 0;

    /** Application error, bad argument. */
    int APP_ERROR_BAD_ARGUMENT          = 1;

    /** Application error, bad command. */
    int APP_ERROR_BAD_COMMAND           = 2;

    /** Application error, resource not found. */
    int APP_ERROR_RSRC_NOT_FOUND        = 3;

    /** Application error, view not found. */
    int APP_ERROR_VIEW_NOT_FOUND        = 4;

    /** Application error, out of memory. */
    int APP_ERROR_OUT_OF_MEMORY         = 5;

    /** Application error, error other. */
    int APP_ERROR_OTHER                 = 100;

    //
    // media errors
    //

    /** Resouce error, error unknown. */
    int RSRC_ERROR_UNKNOWN              = 0;

    /** Resouce error, bad data. */
    int RSRC_ERROR_BAD_DATA             = 1;

    /** Resouce error, bad magic. */
    int RSRC_ERROR_BAD_MAGIC            = 2;

    /** Resouce error, bad version. */
    int RSRC_ERROR_BAD_VERSION          = 3;

    /** Resouce error, connection lost. */
    int RSRC_ERROR_CONNECTION_LOST      = 4;

    /** Resouce error, connection time-out. */
    int RSRC_ERROR_CONNECTION_TIMEOUT   = 5; 

    /** Resouce error, connection failed. */
    int RSRC_ERROR_CONNECT_FAILED       = 6;    

    /** Resouce error, host not found. */
    int RSRC_ERROR_HOST_NOT_FOUND       = 7;

    /** Resouce error, incompatible. */
    int RSRC_ERROR_INCOMPATIBLE         = 8;

    /** Resouce error, not supported. */
    int RSRC_ERROR_NOT_SUPPORTED        = 9;

    /** Resouce error, bad argument. */
    int RSRC_ERROR_BAD_ARGUMENT         = 20;

    /** Resouce error, bad state. */
    int RSRC_ERROR_BAD_STATE            = 21;

    /** Resouce error, error other. */
    int RSRC_ERROR_OTHER                = 100;

    //
    // key codes, KEY_*.  All receivers should generate these key events.
    //

    /** Unknown key ID. */
    int KEY_UNKNOWN			= 0;

    /** TiVo key, reserved for internal use. */
    int KEY_TIVO			= 1;

    /** Up key. */
    int KEY_UP				= 2;

    /** Down key. */
    int KEY_DOWN			= 3;

    /** Left key. */
    int KEY_LEFT			= 4;

    /** Right key. */
    int KEY_RIGHT			= 5;

    /** Select key. */
    int KEY_SELECT			= 6;

    /** Play key. */
    int KEY_PLAY			= 7;

    /** Pause key. */
    int KEY_PAUSE			= 8;

    /** Slow key. */
    int KEY_SLOW			= 9;

    /** Reverse key. */
    int KEY_REVERSE			= 10;

    /** Forward key. */
    int KEY_FORWARD			= 11;

    /** Replay key. */
    int KEY_REPLAY			= 12;

    /** Advance key. */
    int KEY_ADVANCE			= 13;

    /** Thumbs up key. */
    int KEY_THUMBSUP			= 14;

    /** Thumbs down key. */
    int KEY_THUMBSDOWN			= 15;

    /** Volume up key. */
    int KEY_VOLUMEUP			= 16;

    /** Volume down key. */
    int KEY_VOLUMEDOWN			= 17;

    /** Channel up key. */
    int KEY_CHANNELUP			= 18;

    /** Channel down key. */
    int KEY_CHANNELDOWN			= 19;

    /** Mute key. */
    int KEY_MUTE			= 20;

    /** Record key. */
    int KEY_RECORD			= 21;

    /** Live TV key, reserved for internal use. */
    int KEY_LIVETV			= 23;
    
    /** Info key, same code as {@link #KEY_DISPLAY}. */
    int KEY_INFO			= 25;

    /** Display key, same code as {@link #KEY_INFO}. */
    int KEY_DISPLAY			= KEY_INFO;
    
    /** Clear key. */
    int KEY_CLEAR			= 28;

    /** Enter key. */
    int KEY_ENTER			= 29;

    /** Number 0 key. */
    int KEY_NUM0			= 40;

    /** Number 1 key. */
    int KEY_NUM1			= 41;

    /** Number 2 key. */
    int KEY_NUM2			= 42;

    /** Number 3 key. */
    int KEY_NUM3			= 43;

    /** Number 4 key. */
    int KEY_NUM4			= 44;

    /** Number 5 key. */
    int KEY_NUM5			= 45;

    /** Number 6 key. */
    int KEY_NUM6			= 46;

    /** Number 7 key. */
    int KEY_NUM7			= 47;

    /** Number 8 key. */
    int KEY_NUM8			= 48;

    /** Number 9 key. */
    int KEY_NUM9			= 49;


    //
    // optional key codes
    //

    /**
     * Window key, optional, same code as {@link #KEY_OPT_PIP} and {@link
     * #KEY_OPT_ASPECT}.
     */
    int KEY_OPT_WINDOW			= 22;

    /**
     * Picture in picture (PIP) key, optional, same code as {@link
     * #KEY_OPT_WINDOW} and {@link #KEY_OPT_ASPECT}.
     */
    int KEY_OPT_PIP			= KEY_OPT_WINDOW; 

    /**
     * Aspect key, optional, same code as {@link #KEY_OPT_WINDOW} and {@link
     * #KEY_OPT_PIP}.
     */
    int KEY_OPT_ASPECT			= KEY_OPT_WINDOW;

    /** Exit key, reserved for internal use. */
    int KEY_OPT_EXIT			= 24;

    /** List now playing key, reserved for internal use. */
    int KEY_OPT_LIST			= 26;

    /** Guide key, reserved for internal use. */
    int KEY_OPT_GUIDE			= 27;

    /** Stop key, optional. */
    int KEY_OPT_STOP			= 51;

    /** Menu key, optional. */
    int KEY_OPT_MENU			= 52;

    /** Top menu key, optional. */
    int KEY_OPT_TOP_MENU		= 53;

    /** Angle key, optional. */
    int KEY_OPT_ANGLE			= 54;
    
    /** DVD key, reserved for internal use. */
    int KEY_OPT_DVD			= 55;

    //
    // key actions
    //

    /** Key action type, press. */
    int KEY_PRESS                       = 1;

    /** Key action type, repeat. */
    int KEY_REPEAT                      = 2;

    /** Key action type, release*/
    int KEY_RELEASE                     = 3;

    //
    // limits
    //

    /** Protocol limit for the number of stacked views. */
    int LIMIT_VIEW_DEPTH         = 128;

    /** Protocol limit for size of an event, in bytes. */
    int LIMIT_EVENT_NBYTES       = (4*1024);

    /** Protocol limit for size of an image, in bytes. */
    int LIMIT_IMAGE_NBYTES       = (768*1024);

    /** Protocol limit for size of a sound clip, in bytes. */
    int LIMIT_SOUND_NBYTES       = (128*1024);

    /** Protocol limit for size of a text string, in bytes. */
    int LIMIT_TEXT_NBYTES        = (16*1024);

    /** Protocol limit for the number of bytes in a URL. */
    int LIMIT_URL_NBYTES         = 1024;

    /** Protocol limit for the width of an image, in pixels. */
    int LIMIT_IMAGE_WIDTH        = 1024;

    /** Protocol limit for the height of an image, in pixels. */
    int LIMIT_IMAGE_HEIGHT       = 768;

    /** Protocol limit for the point size of a font. */
    int LIMIT_FONT_POINT_SIZE    = 256;

    /** Protocol limit for the lengh of a command, in bytes. */
    int LIMIT_CMD_NBYTES         = ((512+4)*1024);
    
    //
    // Action and Title safe constants
    //

    /** Horizontal action safe part of the screen. */
    int SAFE_ACTION_H	= 32;

    /** Vertical action safe part of the screen. */
    int SAFE_ACTION_V	= 24;

    /** Horizontal title safe part of the screen. */
    int SAFE_TITLE_H	= 64;

    /** Vertical title safe part of the screen. */
    int SAFE_TITLE_V	= 48;
}
